home *** CD-ROM | disk | FTP | other *** search
/ Space & Astronomy / Space and Astronomy (October 1993).iso / mac / VIEWERS / X11 / XLOADIMG.TAR / README < prev    next >
Text File  |  1991-05-20  |  16KB  |  316 lines

  1. XLOADIMAGE - X11 Image Loading Utility
  2.  
  3. WHAT IS IT?
  4.  
  5. This utility will view several types of images under X11, or load
  6. images onto the root window.  The current version supports:
  7.  
  8.     CMU Window Manager raster files
  9.     Faces Project images
  10.     Fuzzy Bitmap (FBM) images
  11.     GEM bit images
  12.     GIF images
  13.     G3 FAX images
  14.     McIDAS areafiles
  15.     MacPaint images
  16.     PC Paintbrush (PCX) images
  17.     Portable Bitmap (PBM, PGM, PPM) images
  18.     Sun monochrome rasterfiles
  19.     Sun color RGB rasterfiles
  20.     Utah Raster Toolkit (RLE) files
  21.     X pixmap files
  22.     X10 bitmap files
  23.     X11 bitmap files
  24.     X Window Dump (except TrueColor and DirectColor)
  25.  
  26. A variety of options are available to modify images prior to viewing.
  27. These options include clipping, dithering, depth reduction, zoom
  28. (either X or Y axis independently or both at once), brightening or
  29. darkening, and image merging.  When applicable, these options are done
  30. automatically (eg a color image to be displayed on a monochrome screen
  31. will be dithered automatically).
  32.  
  33. COMPILING
  34.  
  35. There are a variety of ways to compile xloadimage, depending on what
  36. environment you have.  The building techniques have changed somewhat
  37. from versions earlier than 2.0.
  38.  
  39. If you use gcc you should read this whole section before compiling.
  40.  
  41. If you are compiling under the X11R4 distribution, the apropriate
  42. Imakefile is included.  I recommend using the standard Makefile as it
  43. contains a number of different build targets depending on your
  44. environment.
  45.  
  46. If you're compiling on a BSD system or a system that's mostly BSDish,
  47. use "make std" or just "make".
  48.  
  49. If you're compiling on a System-V system, use "make sysv".  If you
  50. have gcc you may want to use that (read on for caveats) and should use
  51. "make sysv-gcc" or "make sysv-gcc-1-37" as appropriate.
  52.  
  53. If you have gcc on your system, and it's not gcc 1.37, compile via
  54. "make gcc".  Gcc should be used if it works because the
  55. strength-reduction and inline-functions directives dramatically
  56. improve performance of some operations.  Please note that use of gcc
  57. on some systems, particularly Sun-4, may cause problems.
  58.  
  59. If you have gcc 1.37 on your system, compile via "make gcc-1-37".  Gcc
  60. 1.37 has an optimizer bug which causes (at least) GIF image loading to
  61. fail.  This make target adds some extra compilation flags which should
  62. correct this problem.
  63.  
  64. If you run into problems with code compiled with gcc, I suggest trying
  65. the same thing using the standard or System-V target (whichever is
  66. appropriate) before reporting a bug.  Bug fixes are always
  67. appreciated.  PLEASE INCLUDE THE VERSION NUMBER REPORTED BY xloadimage
  68. -version IN ANY BUG REPORT.
  69.  
  70. WORKAROUNDS FOR BROKEN SERVERS
  71.  
  72. Some servers which use odd-depth displays (eg not 1 or a multiple of 8
  73. bits) do not correctly handle a plane mask with GXcopy.  If your
  74. server displays color images in only two colors although it supports
  75. more colors, add a -DSERVER_HAS_BROKEN_PLANEMASK to CFLAGS in the
  76. Makefile.  Some Visual X-19 Turbo displays have this problem; you
  77. should request an updated ROM if you have one of these.  Xloadimage
  78. version 3.0 and later should not exhibit this problem.
  79.  
  80. Xloadimage version 3.0 and later supports all visual types and will
  81. attempt to pick the best visual for a given image.  Sometimes it may
  82. pick a bad visual or you pick one that the server says it knows how to
  83. do but really can't handle.  In either case the -visual option can be
  84. used to force a particular visual.
  85.  
  86. INSTALLATION
  87.  
  88. After compiling and installing xloadimage, I recommend linking or
  89. symlinking to the executable with the names "xview" and "xsetbg".  The
  90. default behavior is slightly different when invoked with these
  91. commands (they're also easier to type).  If you have a public image
  92. area you should consider setting the SYSPATHFILE option in the
  93. makefile and setting up a system-wide configuration file.  See the man
  94. page for information on the format of this file.
  95.  
  96. IMPLEMENTATION
  97.  
  98. Most functions are not particularly fast, and some functions use
  99. simple-minded algorithms deliberately over more advanced ones.  I
  100. stressed portability over all and simplicity over performance,
  101. although many algorithms have become fairly complex over time.  I
  102. believe the result is a usable, portable tool which should serve the
  103. needs of most users.
  104.  
  105. The source code is basically in two parts: image manipulation routines
  106. and everything else.  The image manipulation routines should be
  107. completely independent of X, thus allowing people to use them under
  108. other graphical systems.  No guarantees here, but I tried.
  109.  
  110. Performance-oriented people will notice that some operations are
  111. redundant.  Xloadimage is designed to work fairly quickly for most
  112. operations but in some cases I opted for a cleaner internal design
  113. rather than pure performance.
  114.  
  115. OWNERSHIP
  116.  
  117. I used a modified version of the MIT X Consortium copyright with all
  118. of these functions, thereby allowing full freedom with the code so
  119. long as the copyright notices remain intact.  Free code can be good
  120. code.  All contributions have similar notices.
  121.  
  122. Commercial sites are welcome to use the code even without asking me,
  123. although I'm very happy to hear of this stuff going toward real
  124. products so I appreciate it if anyone who uses some or all of the code
  125. drops me a line.  If you tell me you're using it I'm much more likely
  126. to keep you informed about new versions as well, so it works out well
  127. all around.
  128.  
  129. PRAISE, SUGGESTIONS AND BUG REPORTS
  130.  
  131. Praise, suggestions, and bug reports should go to:
  132.  
  133.     Jim Frost
  134.     Saber Software
  135.     185 Alewife Brook Parkway
  136.     Cambridge, MA  02138
  137.     (617) 924-1985
  138.     jimf@saber.com
  139.     ..!uunet!saber!jimf
  140.  
  141. Please include the version number and sample image data if you are
  142. reporting a bug.
  143.  
  144. Functions implementing new image types are welcomed; mail them to the
  145. same address and I'll do my best to distribute them.  Please include a
  146. small sample image.  Try to send them as public domain so I can keep
  147. the number of differing copyright messages to a minimum -- I'll use my
  148. standard message and leave the implementor's name and information in
  149. the file for credit.  I wouldn't copyright this stuff at all except
  150. that it's a requirement for X11 distribution.
  151.  
  152. If you particularly like xloadimage, feel free to drop me a line.  It
  153. makes me feel good and I get a feel for who does what with it, which
  154. sometimes influences what parts are worked on.
  155.  
  156. THANKS
  157.  
  158. Special thanks to the crew at the Boston University Graphics Lab for
  159. their assistance and sample images, and to bzs@std.com for his simple
  160. dithering algorithm (or what's left of it).  Real special thanks to
  161. Kirk L. Johnson (tuna@athena.mit.edu) for a very nice GIF loader and
  162. dithering routine, to Mark Snitily (zok!mark@apple.com) for 386/ix
  163. compatibility work, to Andreas Stolcke (stolcke@icsib12.berkeley.edu)
  164. for miscellaneous bug fixes, to Anthony A. Datri (datri@convex.com)
  165. for a number of things, to Mark Moraes (moraes@cs.toronto.edu) for
  166. the slideshow colormap fix, to Gregg Townsend (gmt@cs.arizona.edu) for
  167. a suggested dithering routine and other fixes, to Brian Frost
  168. (B1F5814@RIGEL.TAMU.EDU) for changes for VMS, to Chip Horstman for G3
  169. FAX support, to Deron Dann Johnson (dj@eng.sun.com) for fixing the
  170. RetainTemporary bug, to Tom Tatlow (tatlow@dash.enet.dec.com) for
  171. image rotation code, to Mark A. Horstman (mhorstm@sarek.sbc.com) for
  172. tilde expansion in .xloadimagerc files and virtual-root support in
  173. root.c, to Tim Roper (timr@labtam.labtam.oz.au), Graeme Gill
  174. (graeme@labtam.oz.au) for gamma correction and Utah RLE image support,
  175. Mark Majhor (uunet!sequent!markm) for FBM and MacPaint support, Ian
  176. MacPhedran (macphed@dvinci.usask.ca) for PGM and PPM support, Per
  177. Fogelstrom (pf@diab.se) for a fix to send.c, Hans J. Albertsson
  178. (hans@Sweden.Sun.COM) for cleaning up GIF aborting, Graham Hudspith
  179. (gwh@inmos.com) for a geometry patch, Glenn P. Davis
  180. (davis@unidata.ucar.edu) for McIDAS areafile support, Keith S. Pickens
  181. (maxwell.nde.swri.edu!ksp) for fixing the RLE loader to work with the
  182. updated zio package, Mike Douglas (douglas@wilbur.coyote.trw.com) for
  183. normalization, Rod Johnson (johnson@wrl.epi.com) for speedup
  184. suggestions, Hal Peterson (hrp@cray.com) for his Imakefile fix, Matt
  185. Caprile (Matthew.Caprile@ec.bull.fr) for slideshow delay code, Bob
  186. Deroy (rwd@bucrsb.bu.edu) for mondo 24-bit Sun Rasterfile images that
  187. broke everything, Christos S. Zoulas (christo@ee.cornell.edu) for a
  188. first-cut 24-bit implementation, Gerald James Barnes
  189. (gjb@oasis.icl.stc.co.uk) for a first-cut forced-visual
  190. implementation, Michael Campanella (campanella@cvg.enet.dec.com) for
  191. more VMS changes, Kee Hinckley (nazgul@alfalfa.com) for robustness
  192. changes to the g3 and MacPaint loaders and the ZIO package, Tim
  193. Northrup (tim@brspyr1.brs.com) for PC Paintbrush and GEM image
  194. formats, Richard Weidner (richard@elroy.jpl.nasa.gov) for lots of
  195. 24-bit testing, and any others whose names I've missed.
  196.  
  197. HISTORY
  198.  
  199. Patch 01 contained a new Makefile.std, Makefile.gcc, and Imakefile.
  200. It contained a bug-fix to sendImageToX() which allowed bitmaps to be
  201. sent from little-endian machines (eg VAX, 80386) correctly, and a fix
  202. to xbitmapLoad() to allow correct loading of X10 bitmap images.  An
  203. enhancement to imageInWindow() which allowed exiting from image
  204. windows by typing 'q' was submitted by Chris Tengi
  205. (tengi@idunno.princeton.edu) and was included.  The previously missing
  206. file 'patchlevel' was included.
  207.  
  208. Patch 02 contained modifications to the Makefiles, support for the X
  209. Pixmap image type, a different dithering algorithm that didn't blow
  210. the image up (with the old one moved to halftone.c), and a bug fix to
  211. zoom.c to correct problems when zooming bitmaps.
  212.  
  213. Patch 03 contained a new loader for GIF files.  The dither bits array
  214. in dither.c was changed so it worked properly, and both dither.c and
  215. halftone.c had minor bugs fixed.  Merge.c was modified to correct bugs
  216. when merging RGB images.  Pbm.c was modified to handle raw format
  217. images.  Root.c was modified to deny image loads which would change
  218. the root window's colormap.  Send.c was modified to use shared colors
  219. whenever possible and to handle color displays which have depths which
  220. are not a multiple of 8.  Window.c was modified to avoid deleting the
  221. default colormap, allowing proper operation on some servers prior to
  222. X11R3 patchlevel 08.  There were many miscellaneous bug fixes.
  223.  
  224. Patchlevel 04 contained an enhancement to root.c to use
  225. RetainTemporary and KillClient(disp, AllTemporary) so that it could
  226. clean up after itself when reloading.  The -quiet and -zoom options no
  227. longer cause garbage to be displayed for the image title.  A small bug
  228. in new.c that caused incorrect allocation of bitmap images was fixed.
  229. Several calls to XCreateColormap were missing the "visual" parameter
  230. in send.c; this was fixed.  A bug relating to -border and monochrome
  231. displays was fixed.  There were several changes to the Imakefile and
  232. Makefiles.
  233.  
  234. Patchlevel 05 contained enhancements to allow slideshows and
  235. fullscreen viewing, some bug fixes related to scrolling around within
  236. images, Saber-C makefile enhancements, a bug fix to the halftoning
  237. title, and the addition of greyscale Sun Rasterfile support.
  238.  
  239. Patchlevel 06 contained support for G3 FAX images, bug fixes to
  240. merge.c to fix some signed/unsigned errors and clipping problems,
  241. changes to root.c to make previously allocated resources be freed
  242. properly, and a completely new dithering routine.
  243.  
  244. Version 2, patchlevel 00 contained support for MacPaint, FBM, PGM,
  245. PPM, CMU, Utah RLE and XWD image formats, gamma equalization, image
  246. smoothing, and image rotation.  G3 FAX support was modified to cut
  247. down on false positive identifications.  The zio subsystem was
  248. modified to cache reads for performance improvements and to allow
  249. stdin to be used as an input source.  Several loader functions which
  250. did not properly close their files were fixed.  Color slideshows now
  251. work.  Icon titles use an abbreviated titlebar title to enhance
  252. readability.  The resource class name was changed from XLoadImage to
  253. xloadimage to be more predictable.  Several options now propagate to
  254. all images following them if the -slideshow option is specified.
  255.  
  256. Version 2.01 contained several fixes to window.c to work around a bug
  257. in twm/tvtwm which could crash servers.  The resource class name was
  258. changed (again) to Xloadimage to conform with standard class naming
  259. practices.  Several problems with System-V compilation were corrected.
  260. The gcc-1-37 make target was fixed to prevent a double-define.  The
  261. GIF loader was patched to respond better to short GIF files.  The Utah
  262. RLE image loader was patched to work with the updated ZIO package.
  263.  
  264. Version 2.02 added the options -default, -gray, -normalize, and
  265. -private.  The memToVal routines were macro-ized for substantial speed
  266. increases.  The atom used for deleting previously allocated colors for
  267. the -onroot option was changed to correspond to that used by xsetroot.
  268. Dithering and halftoning were changed to use a lookup table for
  269. intensities to speed them up somewhat.  Rle.h was changed to use
  270. memToValLSB() instead of its own byte-swapping algorithm for
  271. portability.  Window.c was modified to eliminate the initial paint,
  272. moving it instead to within ConfigureNotify.  A fix was made to xwd.c
  273. to fix its colormap loader for out-of-order colormaps.  The G3 FAX
  274. identification function was fixed and the G3 loader moved to prior to
  275. the MacPaint loader so that both can be used.  A bug in send.c where
  276. color images using the default colormap would not appear correctly if
  277. the display depth was not a multiple of 8 was corrected.  The default
  278. gamma value used in rle.c was changed from 2 to 1.  There were
  279. miscellaneous portability changes.
  280.  
  281. Version 2.03 added -delay.  Many minor programming errors were cleaned
  282. up.  Hash.c was changed to use image.h instead of local typedefs
  283. (fixing a problem with PPM image loading).  Window.c was changed to
  284. fix a problem with override redirect windows in fullscreen mode,
  285. and refresh problems with some servers in slideshow mode were fixed.
  286. Path.c was modified to ignore directories when searching for files.
  287. Send.c was modified to allow TrueColor and DirectColor visuals.
  288.  
  289. Version 2.03-JPL contained interim code to handle 24-bit TrueColor and
  290. DirectColor displays pending the release of Version 3.0.
  291.  
  292. Version 3.0 added full support for all server types.  Internal support
  293. for 24-bit images was implemented (including the improvement of Sun
  294. Rasterfile and PPM support to use the 24-bit format internally).  Many
  295. modifications to image processing routines to support or make use of
  296. 24-bit images.  A much-improved colormap reduction algorithm replaced
  297. the primitive one in previous versions.  The window display code was
  298. modified to work with the best possible visual.  The window display
  299. code was modified to use backing store when available (and -pixmap was
  300. added to force the old technique).  The -fit option was added to force
  301. an image to be fit into the default colormap if it didn't fit as
  302. supplied.  The -fork option was added to allow automatic
  303. backgrounding.  The -onroot -fullscreen options were modified to
  304. preserve aspect ratio.  The -windowid option was added to allow the
  305. setting of the background pixmap of any window.  The -onroot code was
  306. modified to work with DECWINDOWS servers.  The -normalize option was
  307. improved for color images.  The -slideshow option was removed (and
  308. made the default behavior) and -merge was added to allow more flexible
  309. image merging.  The WM_DELETE protocol is now recognized.  PC
  310. Paintbrush (PCX) and GEM bitmap image formats are now supported.  The
  311. GIF 89a signature is now recognized (although no support for its
  312. additional capabilities has been implemented).
  313.  
  314. Version 3.01 corrected color problems when merging RGB files and fixed
  315. a few small problems.
  316.